home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3 / f90 / pxfexecv.z / pxfexecv
Encoding:
Text File  |  1998-10-30  |  16.4 KB  |  351 lines
  1. PXFEXECV(3F)                                          Last changed: 2-24-98
  2.  
  3.  
  4. NNAAMMEE
  5.      PPXXFFEEXXEECCVV, PPXXFFEEXXEECCVVEE, PPXXFFEEXXEECCVVPP - Executes a new process image file
  6.  
  7. SSYYNNOOPPSSIISS
  8.      SSUUBBRROOUUTTIINNEE PPXXFFEEXXEECCVV ((_p_a_t_h,, _l_e_n_p_a_t_h,, _a_r_g_v,, _l_e_n_a_r_g_v,, _i_a_r_g_c,, _i_e_r_r_o_r))
  9.      IINNTTEEGGEERR _l_e_n_p_a_t_h,, _l_e_n_a_r_g_v((00::_i_a_r_g_c--11)),, _i_a_r_g_c,, _i_e_r_r_o_r
  10.      CCHHAARRAACCTTEERR*_n _p_a_t_h,, _a_r_g_v((00::_i_a_r_g_c--11))
  11.  
  12.      SSUUBBRROOUUTTIINNEE PPXXFFEEXXEECCVVEE ((_p_a_t_h,, _l_e_n_p_a_t_h,, _a_r_g_v,, _l_e_n_a_r_g_v,, _i_a_r_g_c,, _e_n_v,,
  13.      _l_e_n_e_n_v,, _i_e_n_v_c,, _i_e_r_r_o_r))
  14.      IINNTTEEGGEERR _l_e_n_p_a_t_h,, _l_e_n_a_r_g_v((00::_i_a_r_g_c--11)),, _i_a_r_g_c,, _l_e_n_a_r_g_v,, _i_e_n_v_c,, _i_e_r_r_o_r
  15.      CCHHAARRAACCTTEERR*_n _p_a_t_h,, _a_r_g_v((00::_i_a_r_g_c--11)) _e_n_v((_i_e_n_v_c))
  16.  
  17.      SSUUBBRROOUUTTIINNEE PPXXFFEEXXEECCVVPP ((_f_i_l_e,, _l_e_n_f_i_l_e,, _a_r_g_v,, _l_e_n_a_r_g_v,, _i_a_r_g_c,, _i_e_r_r_o_r))
  18.      IINNTTEEGGEERR _l_e_n_f_i_l_e,, _l_e_n_a_r_g_v((00::_i_a_r_g_c--11)),, _i_a_r_g_c,, _i_e_r_r_o_r
  19.      CCHHAARRAACCTTEERR*_n _f_i_l_e,, _a_r_g_v((00::_i_a_r_g_c--11))
  20.  
  21. IIMMPPLLEEMMEENNTTAATTIIOONN
  22.      UNICOS, UNICOS/mk, and IRIX systems
  23.  
  24. DDEESSCCRRIIPPTTIIOONN
  25.      On IRIX systems, this routine is in lliibbffoorrttrraann..ssoo which is linked by
  26.      default when compiling programs with the MIPSpro 7 Fortran 90 compiler
  27.      or when compiling programs with the --ccrraayylliibbss option to the MIPSpro
  28.      7.2 F77 compiler.
  29.  
  30.      The PPXXFFEEXXEECCVV routine uses the eexxeeccvv(2) system call to replace the
  31.      current process image with a new process image.
  32.  
  33.      The PPXXFFEEXXEECCVVEE routine uses the eexxeeccvvee(2) system call to replace the
  34.      current process image with a new process image.  The environment
  35.      variables are not inherited from the calling process image.  The
  36.      environment variables for the new process image are specified by the
  37.      _e_n_v argument.
  38.  
  39.      The PPXXFFEEXXEECCVVPP routine uses the eexxeeccvvpp(2) system call to replace the
  40.      current process image with a new process image.
  41.  
  42.      When using the CF90 compiler or MIPSpro 7 Fortran 90 compiler on
  43.      UNICOS, UNICOS/mk, or IRIX systems, all arguments must be of default
  44.      kind unless documented otherwise.  On UNICOS and UNICOS/mk, default
  45.      kind is KKIINNDD==88 for integer, real, complex, and logical arguments; on
  46.      IRIX, the default kind is KKIINNDD==44.
  47.  
  48.      The following is a list of arguments for these routines:
  49.  
  50.      _p_a_t_h      An input character variable or array element containing the
  51.                pathname of the new process image file.
  52.  
  53.      _l_e_n_p_a_t_h   An input integer variable for the length of _p_a_t_h. If _l_e_n_p_a_t_h
  54.                is zero, trailing blanks are removed.
  55.  
  56.      _f_i_l_e      An input character variable or array element containing the
  57.                file of the new process image file. If _f_i_l_e contains a slash
  58.                character, _f_i_l_e will be used as the pathname for the new
  59.                process image file. Otherwise, the directories listed in the
  60.                PPAATTHH environment variable are searched using each directory
  61.                in _p_a_t_h as a pathname prefix for _f_i_l_e.
  62.  
  63.      _l_e_n_f_i_l_e   An input integer variable for the length of _f_i_l_e. If _l_e_n_f_i_l_e
  64.                is zero, trailing blanks are removed.
  65.  
  66.      _a_r_g_v      An input array of character strings. _a_r_g_v contains the
  67.                arguments to be passed to the new process image.
  68.  
  69.      _l_e_n_a_r_g_v   An input array of integers. Each element in _l_e_n_a_r_g_v contains
  70.                the length of the corresponding character string in _a_r_g_v. If
  71.                an element in _l_e_n_a_r_g_v is zero, the corresponding element in
  72.                _a_r_g_v has all trailing blanks stripped.
  73.  
  74.      _i_a_r_g_c     An input integer variable. _i_a_r_g_c contains the number of
  75.                arguments to pass to the new process image.
  76.  
  77.      _e_n_v       An input array of character strings. _e_n_v contains the
  78.                environment variables for the new process image.
  79.  
  80.      _l_e_n_e_n_v    An input array of integers. Each element in _l_e_n_e_n_v contains
  81.                the length of the corresponding character string in _e_n_v. If
  82.                an element in _l_e_n_e_n_v is zero, the corresponding element in
  83.                _e_n_v will have all trailing blanks stripped.
  84.  
  85.      _i_e_n_v_c     An input integer variable. _i_e_n_v_c contains the number of
  86.                environment variables for the new process image.
  87.  
  88.      _i_e_r_r_o_r    An output integer variable that contains zero if the routine
  89.                was successful or nonzero if the routine was not successful.
  90.  
  91.      The following values may be returned:
  92.  
  93.      EEAACCCCEESS      If the new process file is not a regular file, the new
  94.                  process image file mode denies execution permission, or
  95.                  search permission is denied for a directory listed in the
  96.                  new process image file's path prefix.
  97.  
  98.      EENNOOEENNTT      If one or more components of the new process image file's
  99.                  path name do not exist.
  100.  
  101.      EENNOOEEXXEECC     If the new process image file has the appropriate access
  102.                  permission but an invalid magic number in its header.
  103.  
  104.      EENNOOMMEEMM      If the memory needed to create structures used by the
  105.                  routine could not be allocated.
  106.  
  107.      EEIINNVVAALL      If _l_e_n_p_a_t_h < 0 or _l_e_n_p_a_t_h > LLEENN((_p_a_t_h)) or any element of
  108.                  _l_e_n_a_r_g_v is less than zero or greater than the length of
  109.                  the corresponding element in _a_r_g_v.
  110.  
  111.  
  112.      UNICOS and UNICOS/mk only errors:
  113.  
  114.      EE22BBIIGG       If the number of bytes in _a_r_g_v is greater than the
  115.                  system-imposed limit of AARRGG__MMAAXX found in <<lliimmiittss..hh>>.
  116.  
  117.      EEDDMMOOFFFF      If the process image file is offline, and the data
  118.                  migration facility is not configured in the system.
  119.  
  120.      EEFFAAUULLTT      If the new process image file is not as long as indicated
  121.                  by the size values in its header.
  122.  
  123.      EENNOOMMEEMM      If the new process requires more memory than is allowed by
  124.                  the system-imposed maximum MMAAXXMMEEMM.
  125.  
  126.      EEOOFFFFLLIINN     If the process image file is offline, and automatic file
  127.                  retrieval is disabled.
  128.  
  129.      EEOOFFLLNNDDDD     If the file is offline, and the data management daemon is
  130.                  not currently executing.
  131.  
  132.      EEOOFFLLNNNNRR     If the file is offline, and it is currently unretrievable.
  133.  
  134.  
  135.      IRIX 6.2 only errors:
  136.  
  137.      EE22BBIIGG       If the number of bytes in the new process's argument list
  138.                  is greater than the system-imposed limit AARRGG__MMAAXX (see
  139.                  ssyyssccoonnff(2), iinnttrroo(2), and lliimmiittss..hh).  The argument list
  140.                  limit is the sum of the size of the argument list plus the
  141.                  size of the environment's exported shell variables.
  142.  
  143.      EE22BBIIGG       If the number of bytes in the first line of an interpreter
  144.                  file is greater than 256 bytes.
  145.  
  146.      EEAAGGAAIINN      If there is not enough memory.
  147.  
  148.      EELLIIBBAACCCC     If the required shared library does not have execute
  149.                  permission.
  150.  
  151.      EELLIIBBEEXXEECC    If _p_a_t_h points to a shared library.
  152.  
  153.      EELLIIBBMMAAXX     If the required number of shared libraries exceeds the
  154.                  system imposed maximum SSHHLLIIBB__MMAAXX (see iinnttrroo(2)).
  155.  
  156.      EELLOOOOPP       If too many symbolic links were encountered in translating
  157.                  _p_a_t_h.
  158.  
  159.      EENNAAMMEETTOOOOLLOONNGG
  160.                  If the length of _p_a_t_h exceeds PPAATTHH__MMAAXX found in
  161.                  <<lliimmiittss..hh>>, or the length of a path component exceeds
  162.                  NNAAMMEE__MMAAXX found in <<lliimmiittss..hh>> while PPOOSSIIXX__NNOO__TTRRUUNNCC is in
  163.                  effect.
  164.  
  165.      EENNOOEEXXEECC     If the executable process image file has badly formed
  166.                  header information or the requested virtual addresses are
  167.                  not available.
  168.  
  169.      EENNOOMMEEMM      If the new process image requires more virtual space than
  170.                  is allowed either by the system-imposed maximum or the
  171.                  process imposed maximum PPRROOCCSSIIZZEE__MMAAXX (see ggeettrrlliimmiitt(2) and
  172.                  iinnttrroo(2)).
  173.  
  174.      EEPPEERRMM       If a non-superuser tries to execute a sseettuuiidd file that
  175.                  belongs to some other user and the file system in which
  176.                  the file resides has been mounted with the nnoossuuiidd option
  177.                  (see ffssttaabb(4)), or if a non-superuser attempts to execute
  178.                  a setuid or setgid shell script with a UID or GID that is
  179.                  different than the user's effective UID/GID, and the
  180.                  configured value for nnoo--ssuuiidd--sshheellllss is non-zero (the
  181.                  default) (see iinnttrroo(2) and llbboooott(1M)).
  182.  
  183. EEXXAAMMPPLLEESS
  184.    PPXXFFEEXXEECCVV eexxaammppllee::
  185.      In this example, the program forks and the child calls PPXXFFEEXXEECCVV to
  186.      execute the //bbiinn//ggrreepp process image file. The parent process waits for
  187.      the child to finish executing and then forks again. The child from the
  188.      second fork also calls PPXXFFEEXXEECCVV to execute the //bbiinn//ggrreepp process image
  189.      file. The parent then waits for the child to finish executing.
  190.  
  191.        program test
  192.        integer ipid, ierror, lenpath, lenargv(3), iargc, iretpid
  193.        integer istat
  194.        character*30 path, argv(3)
  195.  
  196.        path = '/bin/grep'
  197.        lenpath = 0
  198.        iargc = 3
  199.        argv(1) = 'grep'
  200.        lenargv(1) = 0
  201.        argv(2) = 'root'
  202.        lenargv(2) = 0
  203.        argv(3) = '/etc/passwd'
  204.        lenargv(3) = 0
  205.  
  206.  
  207.        CALL PXFFORK(ipid,ierror)
  208.        if (ierror .ne. 0) then
  209.           print *,'FAILED: PXFFORK call with error = ',ierror
  210.        else
  211.           if (ipid .eq. 0) then
  212.              print *,'CHILD1: execing grep'
  213.              CALL PXFEXECV(path, lenpath, argv, lenargv, iargc, ierror)
  214.              print *,'FAILED: PXFEXEC call with error = ',ierror
  215.              stop
  216.           else
  217.              print *,'PARENT: waiting for CHILD1'
  218.              CALL PXFWAIT(istat,iretpid,ierror)
  219.              print *,'PARENT: CHILD1 finished. Forking off CHILD2'
  220.              CALL PXFFORK(ipid, ierror)
  221.              if (ipid .eq. 0) then
  222.                  print *,'CHILD2: execing grep'
  223.                  CALL PXFEXECV(path, lenpath, argv, lenargv, iargc, ierror)
  224.                  print *,'FAILED PXFEXEC call with error = ',ierror
  225.                  stop
  226.              else
  227.                  print *,'PARENT: waiting for CHILD2'
  228.                  CALL PXFWAIT(istat,iretpid,ierror)
  229.                  print *,'PARENT: CHILD2 finished.'
  230.                  print *,'PASSED: PXFEXECV normal test'
  231.              endif
  232.           endif
  233.        endif
  234.        end
  235.  
  236.    PPXXFFEEXXEECCVVEE eexxaammppllee::
  237.      In this example, the program forks and the child calls PPXXFFEEXXEECCVVEE to
  238.      execute the //bbiinn//ggrreepp process image file. The parent process waits for
  239.      the child to finish executing and then forks again. The child from the
  240.      second fork also calls PPXXFFEEXXEECCVVEE to execute the //bbiinn//ggrreepp process
  241.      image file. The parent then waits for the child to finish executing.
  242.  
  243.         integer ipid, ierror, lenpath, lenargv(3), iargc, iretpid
  244.         integer istat, errorcondition, lenenv(3), ienvc
  245.         character*30 path, argv(3)
  246.         character*30 env(3)
  247.  
  248.         path = '/bin/grep'
  249.         lenpath = 0
  250.         iargc = 3
  251.         argv(1) = 'grep'
  252.         lenargv(1) = 0
  253.         argv(2) = 'root'
  254.         lenargv(2) = 0
  255.         argv(3) = '/etc/passwd'
  256.         lenargv(3) = 0
  257.         ienvc = 3
  258.         env(1) = 'TERM=vt100'
  259.         lenenv(1) = 0
  260.         env(2) = 'SHELL=/bin/csh'
  261.         lenenv(2) = 0
  262.         env(3) = 'DISPLAY=:0.0'
  263.         lenenv(3) = 0
  264.  
  265.         CALL PXFFORK(ipid,ierror)
  266.         if (ierror .ne. 0) then
  267.            print *,'FAILED: PXFFORK call with error = ',ierror
  268.         else
  269.            if (ipid .eq. 0) then
  270.               print *,'CHILD1: execing grep'
  271.               CALL PXFEXECV(path, lenpath, argv, lenargv, iargc, ierror)
  272.               print *,'FAILED: PXFEXEC call with error = ',ierror
  273.               stop
  274.            else
  275.               print *,'PARENT: waiting for CHILD1'
  276.               CALL PXFWAIT(istat,iretpid,ierror)
  277.               print *,'PARENT: CHILD1 finished. Forking off CHILD2'
  278.               CALL PXFFORK(ipid, ierror)
  279.               if (ipid .eq. 0) then
  280.                  print *,'CHILD2: execing grep'
  281.                  CALL PXFEXECV(path, lenpath, argv, lenargv, iargc, ierror)
  282.                  print *,'FAILED PXFEXEC call with error = ',ierror
  283.                  stop
  284.               else
  285.                  print *,'PARENT: waiting for CHILD2'
  286.                  CALL PXFWAIT(istat,iretpid,ierror)
  287.                  print *,'PARENT: CHILD2 finished.'
  288.                  print *,'PASSED: PXFEXECVP normal test'
  289.               endif
  290.            endif
  291.         endif
  292.         end
  293.  
  294.    PPXXFFEEXXEECCVVPP eexxaammppllee::
  295.      In this example, the program forks and the child calls PPXXFFEEXXEECCVVPP to
  296.      execute the grep process image file. The parent process waits for the
  297.      child to finish executing and then forks again. The child from the
  298.      second fork also calls PPXXFFEEXXEECCVVPP to execute the grep process image
  299.      file. The parent then waits for the child to finish executing.
  300.  
  301.           program test
  302.           integer ipid, ierror, lenfile, lenargv(3), iargc, iretpid
  303.           integer istat
  304.           character*30 file, argv(3)
  305.  
  306.           file = 'grep'
  307.           lenfile = 0
  308.           iargc = 3
  309.           argv(1) = 'grep'
  310.           lenargv(1) = 0
  311.           argv(2) = 'root'
  312.           lenargv(2) = 0
  313.           argv(3) = '/etc/passwd'
  314.           lenargv(3) = 0
  315.  
  316.  
  317.        CALL PXFFORK(ipid,ierror)
  318.        if (ierror .ne. 0) then
  319.           print *,'FAILED: PXFFORK call with error = ',ierror
  320.        else
  321.           if (ipid .eq. 0) then
  322.              print *,'CHILD1: execing grep'
  323.              CALL PXFEXECVP(file, lenfile, argv, lenargv, iargc, ierror)
  324.              print *,'FAILED: PXFEXEC call with error = ',ierror
  325.              stop
  326.           else
  327.              print *,'PARENT: waiting for CHILD1'
  328.              CALL PXFWAIT(istat,iretpid,ierror)
  329.              print *,'PARENT: CHILD1 finished. Forking off CHILD2'
  330.              CALL PXFFORK(ipid, ierror)
  331.              if (ipid .eq. 0) then
  332.                 print *,'CHILD2: execing grep'
  333.                 CALL PXFEXECVP(file, lenfile, argv, lenargv, iargc, ierror)
  334.                 print *,'FAILED PXFEXEC call with error = ',ierror
  335.                 stop
  336.              else
  337.                 print *,'PARENT: waiting for CHILD2'
  338.                 CALL PXFWAIT(istat,iretpid,ierror)
  339.                 print *,'PARENT: CHILD2 finished.'
  340.                 print *,'PASSED: PXFEXECVP normal test'
  341.              endif
  342.           endif
  343.        endif
  344.        end
  345.  
  346. SSEEEE AALLSSOO
  347.      eexxeeccvv(2)
  348.  
  349.      _A_p_p_l_i_c_a_t_i_o_n _P_r_o_g_r_a_m_m_e_r'_s _L_i_b_r_a_r_y _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l, publication
  350.      SR-2165, for the printed version of this man page.
  351.